[[message-listeners]]
= Message Listeners

When you use a xref:kafka/receiving-messages/message-listener-container.adoc[message listener container], you must provide a listener to receive data.
There are currently eight supported interfaces for message listeners.
The following listing shows these interfaces:

[source, java]
----
public interface MessageListener<K, V> { <1>

    void onMessage(ConsumerRecord<K, V> data);

}

public interface AcknowledgingMessageListener<K, V> { <2>

    void onMessage(ConsumerRecord<K, V> data, Acknowledgment acknowledgment);

}

public interface ConsumerAwareMessageListener<K, V> extends MessageListener<K, V> { <3>

    void onMessage(ConsumerRecord<K, V> data, Consumer<?, ?> consumer);

}

public interface AcknowledgingConsumerAwareMessageListener<K, V> extends MessageListener<K, V> { <4>

    void onMessage(ConsumerRecord<K, V> data, Acknowledgment acknowledgment, Consumer<?, ?> consumer);

}

public interface BatchMessageListener<K, V> { <5>

    void onMessage(List<ConsumerRecord<K, V>> data);

}

public interface BatchAcknowledgingMessageListener<K, V> { <6>

    void onMessage(List<ConsumerRecord<K, V>> data, Acknowledgment acknowledgment);

}

public interface BatchConsumerAwareMessageListener<K, V> extends BatchMessageListener<K, V> { <7>

    void onMessage(List<ConsumerRecord<K, V>> data, Consumer<?, ?> consumer);

}

public interface BatchAcknowledgingConsumerAwareMessageListener<K, V> extends BatchMessageListener<K, V> { <8>

    void onMessage(List<ConsumerRecord<K, V>> data, Acknowledgment acknowledgment, Consumer<?, ?> consumer);

}
----

<1> Use this interface for processing individual `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using auto-commit or one of the container-managed xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].

<2> Use this interface for processing individual `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using one of the manual xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].

<3> Use this interface for processing individual `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using auto-commit or one of the container-managed xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].
Access to the `Consumer` object is provided.

<4> Use this interface for processing individual `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using one of the manual xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].
Access to the `Consumer` object is provided.

<5> Use this interface for processing all `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using auto-commit or one of the container-managed xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].
`AckMode.RECORD` is not supported when you use this interface, since the listener is given the complete batch.

<6> Use this interface for processing all `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using one of the manual xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].

<7> Use this interface for processing all `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using auto-commit or one of the container-managed xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].
`AckMode.RECORD` is not supported when you use this interface, since the listener is given the complete batch.
Access to the `Consumer` object is provided.

<8> Use this interface for processing all `ConsumerRecord` instances received from the Kafka consumer `poll()` operation when using one of the manual xref:kafka/receiving-messages/message-listener-container.adoc#committing-offsets[commit methods].
Access to the `Consumer` object is provided.

IMPORTANT: The `Consumer` object is not thread-safe.
You must only invoke its methods on the thread that calls the listener.

IMPORTANT: You should not execute any `Consumer<?, ?>` methods that affect the consumer's positions or committed offsets in your listener; the container needs to manage such information.

